Creating TeachText readme files containing Pictures in the past was something most people didn't like to do. Moreover many people didn't even know how to do it. It was a complex task, juggling resources, using ResEdit. So there weren't too many TeachText files with Pictures about. And yet, TeachText is an ideal instrument for readme documents and online-manuals of all kinds: it launches quickly, uses little memory and above all: everybody's got it.
So I decided to write an application to create TeachText files as easily as it is to create a MacWrite document, using cut&paste-like commands. The result was: TeachText Maker (TTM).
The first thing to do is write your text. You can do this using any word processor, editor or even TTM itself. Don't use fonts, styles ... , just write a plain (ASCII) text.Don't put in carriage returns in after each line, as TTM will wrap the text automatically.
You then save the file as a 'TEXT' file, without line breaks. (e.g. in MsWord choose 'save as...', click on file format and choose TEXT ONLY; in other wordprocessors, choose to put carriage returns after paragraphs only ). Or you could simply just cut and paste the text to TTM.
Use open to get the Textfile into TTM. As it is a textfile, you will get a message that it will open as untitled.
Now you can start preparing your Pictures using your favourite screen capture program, paint and/or draw program. Using Multifinder, you can make one picture at a time and directly cut and insert it into TTM, or else you could prepare all pictures at once, and keep them in your scrapbook for quick access.
(These are programs like Macdraw, Macdraft... I will call the pictures these programs create 'drawings'.)
Simply create the drawing as you like it.
TIP : since teachtext doesn't support multiple fonts, you can create headings for the text in different fonts, by using drawings,just like I did in this file. Don't use any exotic fonts, because the user will probably not have these installed in his system.
(These are programs like Macpaint,...)
Create the painting as you like it. Then cut it out, using the lasso tool or equivalent. This way, you keep the painting as small as possible.
Using a Paint or draw program, you are now ready to put the picture into your TTM document. Copy it from your draw/paint program (using cut or copy) and switch to TTM. Put the cursor on the place you'd like to insert the picture. Now select 'Insert Pict' from the utilities menu. A dialog box will appear:
Select the appropriate radio button, depending on the kind of program you used to create your picture (important!). The picture will be inserted and centred according to the window size.
The dialog box also gives you the option to convert a drawing into a bitmap. If you convert your picture into a bitmap, it will scroll much nicer on the screen, because a bitmap takes less time to redraw each time you advance a line. If your document will mainly be used as an on-line document (like a release note), consider to convert your drawing to a bitmap.
There is one reason why you shouldn't convert the drawings: bitmaps look that much worse on a printer, because they are resolution dependent. So it's up to you to decide what you want: if your document will probably never be printed by the user then convert the drawings to bitmaps, otherwise leave them as they are.
Before I go any further, it is important to understand how things work under the hood. Selecting 'Show ¶' from the utilities menu should help clarify things a bit. If you are making your own document and have inserted a picture, you should see something like this:
Pictures and text are two completely separate entities for teachtext ( likewise for TTM as it uses the same principle). Pictures are not really inserted in the text, they just appear to be. Whenever you use 'insert pict' , an invisible character (called non-breaking space or sticky space) is inserted into the text. When using 'Show ¶' this character will appear as an 'i' in a box . This character is the sign for TTM the show the picture at that very position. Pictures are kept in an ordered list. So e.g. the fifth picture will be shown at the place of the fifth marker. Now here's where things can go wrong. You could accidentally delete the invisible character, causing the picture to be shown at the position of the next marker, messing things up. To avoid this, I suggest you do all editing using the 'Show ¶' option as on. If you still would accidentally delete the marker, do this: Go back to the place where the marker used to be, and press option-space bar. This re-inserts the marker. Everything should be all right now.
Warning: the marker, or sticky space, should ALWAYS be on the first position of a line. If not, it will not be recognized by TTM. This is done for speed reasons. By the contrary, TeachText will recognize any sticky space, whether or not in first position . If things look radically different when you look at the document using TeachText, investigate if you haven't inserted any characters before the markers.
As you see, extra carriage returns are inserted before and after the marker, to make room for the picture. Otherwise text and picture would be shown on top of each other. You can add or delete carriage returns as to make the picture show in the position you like .
After or during the pictures are inserted, you can go on editing. If you want to insert extra text before a picture, make sure your insertion point is really set before the maker. While typing, things might seem to become messy (like typing through the picture, picture doesn't scroll when you add carriage returns before it...) . Don't worry: If you leave the keyboard alone for about 3 seconds, TTM will refresh your screen, and (hopefully) make everything look fine again.
Always remember: text and pictures are two separate entities. Therefore, while editing, you should avoid selecting text ranges over pictures, e.g. for copying. The text will be copied, including the markers, but not the pictures.
To manipulate pictures, use the 'copy pict' and 'delete pict' menu items from the utilities menu.
Copy Pict: Go and put the cursor somewhere below the marker of the picture you want to copy and select 'Copy Pict'. TTM will scroll the picture to the top of the window( so that you can check if it is the right one) and copy it to the clipboard, where it's accessible for other TTM windows or other programs.
Delete Pict: Go and put the cursor somewhere below the marker of the picture you want to delete and select 'Delete Pict'. TTM will scroll the picture to the top of the window and ask you to confirm the deletion. Before deleting, the picture will be copied to the clipboard. Then the marker and the following carriage returns are removed.
Finally save your TTM document, and double click it, to launch TeachText. Print the document, to see how it looks.
*This version of TTM also allows you to print your document. The print-output may differ from the one teachtext will deliver, because TTM uses a wider margin than teachtext. Like teachtext version 1.2, pictures will never be split across page boundaries during printing.
*Fast Typing: when this option is on, the visible pictures will not be redrawn each time you press a key. This may cause pictures to disappear for a while. As usual, if you wait for 3 seconds, the pictures should re-appear. Use this option for changing large portions of text.
That's it. Have fun !
First this : always use the 'Show ¶' option during editing to see what you're doing. This way you can avoid lots of trouble.
Problem : two pictures or a picture and text overlap
Solution : Insert extra carriage returns .
Problem : the pictures don't appear in the right places.
Solution: You have deleted a marker, or the maker is not on the first position of a line. Re-insert the marker, pressing option-space bar, or delete any preceding characters.
Problem : You've copied a text range to another program or another position, but the pictures don't appear.
Solution : TTM doesn't work like this. Use the utilities menu for picture manipulation. Don't select any text over picture boundaries, and make sure you don't copy markers.
Problem : the screen looks messy when editing.
Solution : stop typing for 3 seconds. Everything should be back in order.
Problem : TTM copies or deletes the wrong pictures.
Solution : TTM searches your text from the insertion point upwards to the first marker it meets. This will be the selected picture. TTM will scroll this picture into view to allow you to check if it's the right one. If there are no pictures, or there is a marker without a picture, TTM will do nothing.
Problem : the text gets cut off.
Solution: TTM and TeachText don't allow texts larger than 32000 characters. Make several smaller documents out of your big document. TTM also doesn't allow more than 512 pictures, but I guess that should be enough for most purposes .
Problem : Pictures look great in TTM but overlap with text in TeachText.
Solution : Teachtext uses the default application font. The default application font is stored in your PRAM. If you have changed this font (willing or unwilling) from geneva to something else, things will definitely go wrong. Zap your Pram (by holding down command-option-shift while opening your control panel).
Problem: Some macdraw features, like arrows on a line don't appear correctly in TTM.
Solution: copy the picture to a paint program before inserting into TTM.
This program is shareware. This means you can distribute it freely (see below), but if you use it, you must pay for it.
European users:
----------------
shareware fee:
* $10 or equivalent in your currency (cash or money order)
* cheques:Eurocheques in Belgian Franks ONLY: BEF 300,-
Users outside Europe:
----------------------
shareware fee:
* $15
* please send NO cheques, as banks tend to charge substantial amounts of money for cashing foreign cheques. I do would like to keep some of the money you send me :-) . Send cash or money order only.
ShareWare User advantages
-----------------------------
* You are allowed to use any (future) version of TeachText Maker.
* Shareware users are personally notified of the release of the next version of TTM. You will be offered a disk at costprice.
* * At any time I might decide not to distribute the next version via the usual ShareWare channels, like this version, but exclusively and directly to registered users. If you want to be sure to get the next version, you'll have to become a registered shareware user !
You can spread this version to anybody you like (the more, the better) as long as you keep this in mind:
(1) it must be kept together with this unmodified document.
(2) You don't ask any money for it, except for possible distribution costs. People with commercial intentions should contact me to work something out.
You have my permission to upload this version to online services, such as CompuServe, GEnie, MacNet, DELPHI, etc.
Send shareware fees, bug reports, suggestions and comments, or just a letter (I like getting foreign mail) to:
Karl Pottie
Orkaanstraat 21
B-8800 Rumbeke- Roeselare
Belgium - Europe
------------------
version history:
version 1.0
----------
original version
version 1.1
----------
* printing is now included.
* you can now directly import pictures from draw/paint programs, the complex picture pre-processing is now done by TTM.
* delete pict: the carriage returns after the insertion point will be deleted.
* 'fast typing' option is now included.
* basic search/replace facilities are provided.
* suggested memory size (multifinder) is filled out.
